Integración avanzada

Las siguientes características son opcionales y las podés utilizar en tus integraciones.

Para hacer un uso correcto de la API consultar base_url en la sección Ambientes/Checkout.

Monto del envío

Al crear una orden desde el endpoint api/v2/orders, tenes la posibilidad de sumar el costo del envío y mostrarlo como un ítem dentro del detalle de elementos.

Configuración

Para configurarlo, basta con agregar el nodo shipping con el nombre name y el sub nodo price con el valor del monto del envío y la moneda a utilizar.

    "shipping": {
        "name": "Envio por Correo Argentino",
        "price": {
            "currency": "032",
            "amount": 601
        }
    }

Detalles

Campo	Tipo de campo	Puede ser nulo
name	string	si
currency	string	No
amount	integer	No

Ejemplo

php
node
curl

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://{base_url}/api/v2/orders',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "data": {
    "attributes": {
      "currency": "032",
      "shipping": {
        "name": "Precio fijo",
        "price": {
          "currency": "032",
          "amount": 2000
        }
      },
      "items": [{
        "id": 31,
        "name": "Silla Eames Base Madera",
        "unitPrice": {
          "currency": "032",
          "amount": 1000
        },
        "quantity": 1
      }]
    }
  }
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer XXXXXX',
    'Content-Type: application/vnd.api+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
'method': 'POST',
'url': 'https://{base_url}/api/v2/orders',
'headers': {
  'Authorization': 'Bearer XXXXXX',
  'Content-Type': 'application/vnd.api+json'
},
body: JSON.stringify({
  "data": {
    "attributes": {
      "currency": "032",
      "shipping": {
        "name": "Precio fijo",
        "price": {
          "currency": "032",
          "amount": 2000
        }
      },
      "items": [
        {
          "id": 31,
          "name": "Silla Eames Base Madera",
          "unitPrice": {
            "currency": "032",
            "amount": 1000
          },
          "quantity": 1
        }
      ]
    }
  }
})
  };
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});

    curl --location --request POST 'https://{base_url}/api/v2/orders'     --header 'Authorization: Bearer XXXXXX'     --header 'Content-Type: application/vnd.api+json'     --data-raw '{
      "data": {
        "attributes": {
          "currency": "032",
          "shipping": {
            "name": "Precio fijo",
            "price": {
              "currency": "032",
              "amount": 2000
            }
          },
          "items": [{
            "id": 31,
            "name": "Silla Eames Base Madera",
            "unitPrice": {
              "currency": "032",
              "amount": 1000
            },
            "quantity": 1
          }]
        }
      }
    }'

URL de retorno

Al finalizar el proceso de pago, tienes la opción de redireccionar al comprador tanto para pagos aprobados como para pagos rechazados.

Configuracion

Esta característica da la opción de sumar el nodo redirect_urls y definir dentro un link para success y un link para failed.

    "redirect_urls": {
        "success": "https://www.mitienda.com/?ref=ok",
        "failed": "https://www.mitienda.com/?ref=fallo"
    }

Detalles

Campo	Tipo de campo	Puede ser nulo
success	string	si
failed	string	si

Ejemplo

php
node
curl

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://{base_url}/api/v2/orders',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "data": {
    "attributes": {
      "redirect_urls": {
        "success": "https:\\/\\/www.mitienda.com\\/?ref=ok",
        "failed": "https:\\/\\/www.mitienda.com\\/?ref=fallo"
      },
      "currency": "032",
      "items": [{
        "id": 31,
        "name": "Silla Eames Base Madera",
        "unitPrice": {
          "currency": "032",
          "amount": 1000
        },
        "quantity": 1
      }]
    }
  }
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer XXXXXX',
    'Content-Type: application/vnd.api+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
'method': 'POST',
'url': 'https://{base_url}/api/v2/orders',
'headers': {
  'Authorization': 'Bearer XXXXXX',
  'Content-Type': 'application/vnd.api+json'
},
body: JSON.stringify({
  "data": {
    "attributes": {
      "redirect_urls": {
        "success": "https://www.mitienda.com/?ref=ok",
        "failed": "https://www.mitienda.com/?ref=fallo"
      },
      "currency": "032",
      "items": [
        {
          "id": 31,
          "name": "Silla Eames Base Madera",
          "unitPrice": {
            "currency": "032",
            "amount": 1000
          },
          "quantity": 1
        }
      ]
    }
  }
})
  };
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});

    curl --location --request POST 'https://{base_url}/api/v2/orders'     --header 'Authorization: Bearer XXXXXX'     --header 'Content-Type: application/vnd.api+json'     --data-raw '{
      "data": {
        "attributes": {
          "redirect_urls": {
            "success": "https://www.mitienda.com/?ref=ok",
            "failed": "https://www.mitienda.com/?ref=fallo"
          },
          "currency": "032",
          "items": [{
            "id": 31,
            "name": "Silla Eames Base Madera",
            "unitPrice": {
              "currency": "032",
              "amount": 1000
            },
            "quantity": 1
          }]
        }
      }
    }'

Webhook URL

Sirve para que al momento de finalizar un pago, notifiquemos el estado del mismo.

Configuracion

Simplemente agregar la key webhookUrl en la raíz de attributes y colocar la URL al cual enviaremos la notificación.

"webhookUrl": "https://www.midominio.com/?ref=soyunhook"

Detalles

Campo	Tipo de campo	Puede ser nulo	Longitud
webhookUrl	string	sí	255

Ejemplo

php
node
curl

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://{base_url}/api/v2/orders',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "data": {
    "attributes": {
      "redirect_urls": {
        "success": "https:\\/\\/dominio.com\\/?ref=ok",
        "failed": "https:\\/\\/dominio.com\\/?ref=fallo"
      },
      "webhookUrl": "https:\\/\\/dominio.com\\/?ref=soyunhook",
      "currency": "032",
      "items": [{
        "id": 31,
        "name": "Silla Eames Base Madera",
        "unitPrice": {
          "currency": "032",
          "amount": 1000
        },
        "quantity": 1
      }]
    }
  }
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer XXXXXX',
    'Content-Type: application/vnd.api+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
'method': 'POST',
'url': 'https://{base_url}/api/v2/orders',
'headers': {
  'Authorization': 'Bearer XXXXXX',
  'Content-Type': 'application/vnd.api+json'
},
body: JSON.stringify({
  "data": {
    "attributes": {
      "redirect_urls": {
        "success": "https://dominio.com/?ref=ok",
        "failed": "https://dominio.com/?ref=fallo"
      },
    "webhookUrl": "https://dominio.com/?ref=soyunhook",
      "currency": "032",
      "items": [
        {
          "id": 31,
          "name": "Silla Eames Base Madera",
          "unitPrice": {
            "currency": "032",
            "amount": 1000
          },
          "quantity": 1
        }
      ]
    }
  }
})
  };
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});

    curl --location --request POST 'https://{base_url}/api/v2/orders'     --header 'Authorization: Bearer XXXXXX'     --header 'Content-Type: application/vnd.api+json'     --data-raw '{
      "data": {
        "attributes": {
          "redirect_urls": {
            "success": "https://dominio.com/?ref=ok",
            "failed": "https://dominio.com/?ref=fallo"
          },
          "webhookUrl": "https://dominio.com/?ref=soyunhook",
          "currency": "032",
          "items": [{
            "id": 31,
            "name": "Silla Eames Base Madera",
            "unitPrice": {
              "currency": "032",
              "amount": 1000
            },
            "quantity": 1
          }]
        }
      }
    }'

Estados del Webhook

Cuando el webhook notifica sobre el estado de una orden de compra o una intención de pago, puede devolver los siguientes estados (order.status), cada uno indicando una situación específica en el ciclo de vida de la orden o del pago:

PENDING: La orden de compra ha sido creada y la intención de pago está pendiente. Esto significa que el usuario aún no ha completado el proceso de pago.
EXPIRED: La intención de pago ha alcanzado un estado de "FAILED" o "EXPIRED". Este estado se utiliza para indicar que el tiempo disponible para realizar el pago ha expirado o que el intento de pago no fue exitoso.
FAILED_CHECKOUT: La intención de pago está en estado "ERROR". Esto puede ocurrir por diversos motivos relacionados con el proceso de checkout, como problemas con los datos de pago proporcionados por el usuario.
FAILED: Se presenta cuando el proceso de creación de la orden falla, usualmente debido a un fallo en la creación de la intención de pago. Este estado indica problemas en las etapas preliminares antes de que el usuario intente realizar el pago.
SUCCESS: La intención de pago ha sido completada satisfactoriamente. Esto indica que el pago ha sido procesado y aceptado.

Cada uno de estos estados requiere una gestión específica por parte del sistema que recibe las notificaciones del webhook, asegurando que se manejen adecuadamente las distintas situaciones que pueden presentarse en el proceso de compra y pago.

Ejemplo de POST al WebHook en caso de éxito

    {
      "data": {
        "type": "Payment",
        "order": {
          "uuid": "ea138a99-c9df-44a5-b2bf-09e5db6f8d0c",
          "status": "SUCCESS",
          "source": "app_payment_link"
        },
        "payment": {
          "id": 1823,
          "authorizationCode": "901159",
          "refNumber": "62b4a8ff60fee",
          "status": "APPROVED"
        }
      }
    }

Ejemplo de POST al WebHook en caso de error

    {
      "data": {
        "type": "Payment",
        "order": {
          "uuid": "bd499ea5-79f8-4f18-b18d-dfbef7987f52",
          "status": "PENDING",
          "source": "api_checkout"
        },
        "payment": {
          "id": 7364888,
          "refNumber": "65df288a484b5",
          "status": "DENIED"
        }
      }
    }

Nota

El WebHook intentará realizar 4 llamados al endpoint especificado en un lapso aproximado de 2 minutos entre cada llamado. Esto se hace para asegurar la entrega del mensaje en caso de que el primer intento falle. Es importante tener en cuenta este comportamiento para la gestión adecuada de los mensajes recibidos.

expireLimitMinutes

Establece un tiempo limite para realizar el pago. Una vez vencido dicho tiempo, el pago ya no podrá realizarse.

Consideraciones importantes sobre `expireLimitMinutes`

Cuando se configura expireLimitMinutes para establecer un tiempo límite para realizar el pago, es importante tener en cuenta el comportamiento del sistema una vez que se supera este tiempo límite:

Si el checkout se abre luego de haber pasado el tiempo de expiración: La página mostrará un error indicando "Tu link de pago expiró". Esto significa que el usuario no podrá proceder con el pago debido a que el tiempo configurado para realizarlo ha sido superado.
Si el checkout es abierto inmediatamente y el pago se intenta realizar una vez pasado el tiempo de expiración: En este caso, a pesar de que el usuario haya iniciado el proceso de pago dentro del tiempo límite, si el pago se efectúa después de este tiempo, la página mostrará un mensaje de error "Tuvimos un inconveniente en nuestro sistema".

En cualquiera de los dos escenarios mencionados anteriormente, no se realizará ningún llamado al webhook. Esto es crucial para la gestión de notificaciones y debe ser tenido en cuenta al implementar la lógica de recepción de mensajes en el servidor.

Configuración

Agregar la key expireLimitMinutes en la raíz de attributes y colocar el valor expresado en minutos.

{
  "expireLimitMinutes": 14400
}

Detalles

Campo	Tipo de campo	Puede ser nulo
expireLimitMinutes	integer	No

Ejemplo

php
node
curl

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://{base_url}/api/v2/orders',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "data": {
    "attributes": {
      "redirect_urls": {
        "success": "https:\\/\\/dominio.com\\/?ref=ok",
        "failed": "https:\\/\\/dominio.com\\/?ref=fallo"
      },
      "currency": "032",
      "items": [{
        "id": 31,
        "name": "Silla Eames Base Madera",
        "unitPrice": {
          "currency": "032",
          "amount": 1000
        },
        "quantity": 1
      }],
      "expireLimitMinutes": 14400
    }
  }
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer XXXXXX',
    'Content-Type: application/vnd.api+json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

var request = require('request');
var options = {
'method': 'POST',
'url': 'https://{base_url}/api/v2/orders',
'headers': {
  'Authorization': 'Bearer XXXXXX',
  'Content-Type': 'application/vnd.api+json'
},
body: JSON.stringify({
  "data": {
    "attributes": {
      "redirect_urls": {
        "success": "https://dominio.com/?ref=ok",
        "failed": "https://dominio.com/?ref=fallo"
      },
      "currency": "032",
      "items": [
        {
          "id": 31,
          "name": "Silla Eames Base Madera",
          "unitPrice": {
            "currency": "032",
            "amount": 1000
          },
          "quantity": 1
        }
      ],
      "expireLimitMinutes": 14400
    }
  }
})
  };
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});

    curl --location --request POST 'https://{base_url}/api/v2/orders'     --header 'Authorization: Bearer XXXXXX'     --header 'Content-Type: application/vnd.api+json'     --data-raw '{
      "data": {
        "attributes": {
          "redirect_urls": {
            "success": "https://dominio.com/?ref=ok",
            "failed": "https://dominio.com/?ref=fallo"
          },
          "currency": "032",
          "items": [{
            "id": 31,
            "name": "Silla Eames Base Madera",
            "unitPrice": {
              "currency": "032",
              "amount": 1000
            },
            "quantity": 1
          }],
          "expireLimitMinutes": 14400
        }
      }
    }'

Integración avanzada

Monto del envío​

Configuración​

Detalles​

Ejemplo​

URL de retorno​

Configuracion​

Detalles​

Ejemplo​

Webhook URL​

Configuracion​

Detalles​

Ejemplo​

Estados del Webhook​

Ejemplo de POST al WebHook en caso de éxito​

Ejemplo de POST al WebHook en caso de error​

Nota​

expireLimitMinutes​

Consideraciones importantes sobre expireLimitMinutes​

Configuración​

Detalles​

Ejemplo​

Monto del envío

Configuración

Detalles

Ejemplo

URL de retorno

Configuracion

Detalles

Ejemplo

Webhook URL

Configuracion

Detalles

Ejemplo

Estados del Webhook

Ejemplo de POST al WebHook en caso de éxito

Ejemplo de POST al WebHook en caso de error

Nota

expireLimitMinutes

Consideraciones importantes sobre `expireLimitMinutes`

Configuración

Detalles

Ejemplo